home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.1 / perlpod.1 < prev    next >
Text File  |  1995-07-25  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4.      PPPPEEEERRRRLLLLPPPPOOOODDDD((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLPPPPOOOODDDD((((1111))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           pod - plain old documentation
  10.  
  11.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  12.           A pod-to-whatever translator reads a pod file paragraph by
  13.           paragraph, and translates it to the appropriate output
  14.           format.  There are three kinds of paragraphs:
  15.  
  16.           o+   A verbatim paragraph, distinguished by being indented
  17.               (that is, it starts with space or tab).  It should be
  18.               reproduced exactly, with tabs assumed to be on 8-column
  19.               boundaries.  There are no special formatting escapes, so
  20.               you can't italicize or anything like that.  A \ means \,
  21.               and nothing else.
  22.  
  23.           o+   A command.  All command paragraphs start with "=",
  24.               followed by an identifier, followed by arbitrary text
  25.               that the command can use however it pleases.  Currently
  26.               recognized commands are
  27.  
  28.                   =head1 heading
  29.                   =head2 heading
  30.                   =item text
  31.                   =over N
  32.                   =back
  33.  
  34.  
  35.           o+   An ordinary block of text.  It will be filled, and maybe
  36.               even justified.  Certain interior sequences are
  37.               recognized both here and in commands:
  38.  
  39.                   I<text>     italicize text, used for emphasis or variables
  40.                   B<text>     embolden text, used for switches and programs
  41.                   S<text>     text contains non-breaking spaces
  42.                   C<code>     literal code
  43.                   L<name>     A link (cross reference) to name
  44.                                   L<name>             manpage
  45.                                   L<name/ident>       item in manpage
  46.                                   L<name/"sec">       section in other manpage
  47.                                   L<"sec">            section in this manpage
  48.                                                       (the quotes are optional)
  49.                   F<file>     Used for filenames
  50.                   Z<>         A zero-width character
  51.  
  52.               That's it.  The intent is simplicity, not power.  I
  53.               wanted paragraphs to look like paragraphs (block
  54.               format), so that they stand out visually, and so that I
  55.               could run them through fmt easily to reformat them
  56.               (that's F7 in my version of vvvviiii).  I wanted the
  57.               translator (and not me) to worry about whether " or ' is
  58.               a left quote or a right quote within filled text, and I
  59.               wanted it to leave the quotes alone dammit in verbatim
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 6/30/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      PPPPEEEERRRRLLLLPPPPOOOODDDD((((1111))))  UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000))))  PPPPEEEERRRRLLLLPPPPOOOODDDD((((1111))))
  71.  
  72.  
  73.  
  74.               mode, so I could slurp in a working program, shift it
  75.               over 4 spaces, and have it print out, er, verbatim.  And
  76.               presumably in a constant width font.
  77.  
  78.               In particular, you can leave things like this verbatim
  79.               in your text:
  80.  
  81.                   Perl
  82.                   FILEHANDLE
  83.                   $variable
  84.                   function()
  85.                   manpage(3r)
  86.  
  87.               Doubtless a few other commands or sequences will need to
  88.               be added along the way, but I've gotten along
  89.               surprisingly well with just these.
  90.  
  91.               Note that I'm not at all claiming this to be sufficient
  92.               for producing a book.  I'm just trying to make an
  93.               idiot-proof common source for nroff, TeX, and other
  94.               markup languages, as used for online documentation.
  95.               Both ppppoooodddd2222hhhhttttmmmmllll and ppppoooodddd2222mmmmaaaannnn translators exist.
  96.  
  97.      AAAAuuuutttthhhhoooorrrr
  98.           Larry Wall
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 6/30/95)
  130.  
  131.  
  132.  
  133.